---
title: Version 3.x
description:
  Explore the changelog for Chakra UI version 3.x. Learn about the latest
  features, bug fixes, and improvements.
---

## [3.21.0](./#3.21.0) - 2025-06-11

### Added

- Add support new entrypoint for `/theme` which allows for incremental loading
  of component recipes to avoid bloating the theme with unused components.

  > This is mostly for bundle size optimization.

  For example, if you want just the `button` recipe to be included in your
  bundle, you can cherry-pick the recipe you need like this:

  ```tsx
  import { createSystem, defaultBaseConfig } from "@chakra-ui/react"
  import { buttonRecipe } from "@chakra-ui/react/theme"

  export const system = createSystem(defaultBaseConfig, {
    theme: {
      recipes: {
        button: buttonRecipe,
      },
    },
  })
  ```

### Fixed

- **File Upload**: Prevented `undefined` in `acceptedFiles` when no files
  accepted

- **Select**: Fixed issue where highlighted item could be cleared when
  navigating up/down the list with keyboard

- **Tabs**: Fixed issue where tabs with links should not trigger tab change upon
  cmd/middle click

- **Menu**: Fixed issue where `Menu.ItemText` could not be used with `Menu.Item`

## [3.20.0](./#3.20.0) - 2025-06-06

### Added

- **File Upload**: Added support for transforming uploaded files via
  `transformFiles` context property.

- **Quote**: Export `Quote` typography component and its types

### Fixed

- **System**: Allow `undefined` for optional properties in CSS and recipe types

- **Color Picker**: Fixed issue where value change end event is invoked when
  committing via an input.

- **Toast**: Fixed issue where calling `toast.remove()` without an id shows a
  TypeScript error.

- **Field**: Fixed issue where helper text and error text could not be detected
  in shadow DOM environments.

- **Slider**

  - Fixed issue where `minStepsBetweenThumbs` isn't computed correctly when
    interacting with pointer or keyboard.
  - Fixed issue where `Shift` + `ArrowRight` set value to `0` instead of `max`
    when step is too large (e.g. `20`).
  - Fixed issue where `onValueChangeEnd` doesn't return the latest value when
    dragging very fast.
  - Fixed issue where slider could throw a error when rendered in an popover or
    dialog.

- **Combobox**: Fixed issue where `onInputValueChange` doesn't get called when
  `autoFocus` is set to `true`

- **Pin Input**: Fixed issue where input padding could cause clipping of the
  text when `fontSize` is increased.

- **Checkbox**: Export `CheckboxRootProviderProps` type

- **Charts**: Fixed issue where `formatter` prop doesn't take effect in the
  tooltip

## [3.19.2](./#3.19.2) - 2025-06-02

### Fixed

- **System**: add explicit `undefined` to generated types to support TS
  `exactOptionalPropertyTypes`

- **Drawer**: Fix drawer close animation in RTL

- **Button**

  - Fix layout issue when in loading state with icons by using
    `display: contents` and `visibility: hidden`
  - Add `data-loading` attribute when `loading` is `true` so allow styling
    loading state with `_loading` pseudo prop

- **Input**: Fix issue where invalid styles don't persist for `variant=flushed`

## [3.19.1](./#3.19.1) - 2025-05-17

### Fixed

- **System**: Fix issue where some svg element props tend to be treated as style
  props

- **Checkbox**: Use consistent cursor for checkbox and radio group

## [3.19.0](./#3.19.0) - 2025-05-15

### Added

- **Combobox [New]** Add `Combobox` component for autocomplete text entry.

```tsx
<Combobox.Root>
  <Combobox.Label />
  <Combobox.Control>
    <Combobox.Input />
    <Combobox.IndicatorGroup>
      <Combobox.ClearTrigger />
      <Combobox.Trigger />
    </Combobox.IndicatorGroup>
  </Combobox.Control>
  <Portal>
    <Combobox.Positioner>
      <Combobox.Content>
        <Combobox.Item />
      </Combobox.Content>
    </Combobox.Positioner>
  </Portal>
</Combobox.Root>
```

### Fixed

- **Progress Circle**: Fix issue where progress circle transition was not
  smooth.

## [3.18.0](./#3.18.0) - 2025-05-14

### Added

- **DownloadTrigger [New]** Add `DownloadTrigger` component to help download
  file contents.

### Fixed

- **System**

  - Fix issue where passing `d` prop to `chakra.path` adds it to styles not as a
    direct attribute.
  - Fix issue where responsive semantic tokens did not get applied.

- **Select**: Fix issue where indicator group doesn't align correctly in RTL
  layouts.

## [3.17.0](./#3.17.0) - 2025-05-01

### Added

- **Toast**: Added toast queuing when the max limit is reached:

  - New toasts were queued instead of dropped
  - Queued toasts were shown when space became available
  - Queue cleared when all toasts were removed

### Fixed

- **Breadcrumb**: Prevent screen reader from reading the separator

- **SegmentGroup**: Fix issue where `disabled` prop was not being applied to
  `SegmentGroup.Items`

- **RatingGroup**: Fix issue where half-filled icons were not being displayed
  correctly in RTL

- **Collapsible**: Fixed issue in React.js `<= v18.x` where collapse animation
  might not work as expected

## [3.16.1](./#3.16.1) - 2025-04-20

### Fixed

- **Dialog, Drawer**: Use correct z-index for dialog and drawer backdrop

- **SegmentGroup**: Fix issue where `orientation` prop to `SegmentGroup.Root`
  doesn't work as expected.

## [3.16.0](./#3.16.0) - 2025-04-14

### Added

- **Global CSS**: Improve text selection contrast

- **System**

  - Fix issue where `borderEnd` shorthand was not working despite `borderStart`
    being present
  - Fix issue where `system.cva` return type was incorrect
  - Soften the focus ring for all color palettes

- **Dialog, Drawer**: Fix issue where `z-index` was not being applied correctly

- **[Beta] createOverlay**: Add `createOverlay` utility for programmatically
  controlling overlay components (Dialog, Drawer, etc.)

## [3.15.1](./#3.15.1) - 2025-04-07

### Fixed

- **General**: Ensure types are consistent with React 19
- **Dialog, Drawer**: Fix issue where backdrop could overlap positioner when
  re-opened quickly
- **CLI**: Improve CLI response when passing an unknown snippet id

### Changed

- **BarList, BarSegment**: Rename `showTooltip` with `tooltip` prop to support
  custom tooltips.

## [3.15.0](./#3.15.0) - 2025-03-29

### Added

- **Charts**: Initial release of the `@chakra-ui/charts` package.

### Changed

- **useMediaQuery**: Fix type signature to allow skipping the second argument

- **RadioCard**: Fix accessibility issue due to html structure

- **Slider**

  - Add support for `origin: end` to align the thumb to the end of the track
  - Expose `thumbSize` as CSS variables in the root element. Can be useful for
    styling the slider

- **Menu**
  - Added `onSelect` event to the `Menu.Item` component
  - Ensure menu items have unique IDs to improve accessibility and HTML
    validation

## [3.14.2](./#3.14.2) - 2025-03-24

### Fixed

Fix potential import error from `@zag-js/utils` in `@ark-ui/react`.

## [3.14.1](./#3.14.1) - 2025-03-24

### Fixed

- **System**: Fix issue where output of `<system>.css(...)` from Chakra UI can't
  be assigned to `Interpolation<Theme>` from `@emotion/react`.

- **General**: Bump `@ark-ui/react` to latest version.

## [3.14.0](./#3.14.0) - 2025-03-14

### Changed

- **General**: Improve render performance by upgrading to the latest Ark UI v5.
  This brings a **1.5x - 4x** improvements across components. Learn more from
  the
  [Ark UI v5 changelog](https://ark-ui.com/react/docs/overview/changelog#500---2025-03-06).

- **RadioGroup**: Allow passing `null` as a valid value to clear the value. This
  means the signature of `onValueChange` now supports `string | null` instead of
  just `string`.

  > This might be a potential breaking TS change but it's a needed change to
  > allow clearing the value.

## [3.13.0](./#3.13.0) - 2025-03-13

### Added

- **ColorPicker**

  - Add support for `ColorPicker.ChannelText` component
  - Add `ColorPicker.EyeDropper` component that wraps `IconButton`
  - Add `ColorPicker.Slider` and `ColorPicker.Input` shortcut components to
    reduce LOC.

- **InputGroup**

  - Export directly from the `@chakra-ui/react` package

- **Pagination**

  - Add `Pagination.Items` shortcut component to render the number of pages
    based on the `count` and `pageSize` props.
  - Add `Pagination.PageText` component to render the current page and total
    pages.

## [3.12.0](./#3.12.0) - 2025-03-10

### Added

- **FileUpload**

  - Add `FileUpload.FileText` to render the list of uploaded file names.
  - Add `FileUpload.Items` shorcut component to render the list of uploaded
    files.
  - Add `FileUpload.List` shortcut component that combines `FileUpload.Items`
    and `FileUpload.ItemGroup`.

## [3.11.0](./#3.11.0) - 2025-03-09

### Fixed

- **Accordion**

  - Fix issue where `Accordion.ItemTrigger` doesn't apply `textAlign: start`

### Added

- **SegmentGroup**

  - Add new `SegmentGroup.Items` shortcut component to render multiple
    `SegmentGroup.Item` components based on the `items` prop

## [3.10.0](./#3.10.0) - 2025-03-08

### Changed

- **Menu**

  - Set the default children of `Menu.Arrow` to `Menu.ArrowTip`, reducing LOC in
    common use cases.

- **HoverCard**

  - Set the default children of `HoverCard.Arrow` to `HoverCard.ArrowTip`,
    reducing LOC in common use cases.

- **Dialog, Drawer**

  - Update recipe to include absolute positioning styles for close trigger,
    instead of relying on snippet styles.

## [3.9.0](./#3.9.0) - 2025-03-05

### Added

- **Skeleton** Bring back `SkeletonCircle` and `SkeletonText` components from
  v2.

- **Switch**

  - Transition background color when checked
  - Set `Switch.Control` to include `Switch.Thumb` as its default children,
    reducing LOC in common use cases.

- **Checkbox**

  - Set `Checkbox.Control` to include `Checkbox.Indicator` as its default
    children, reducing LOC in common use cases.

- **NumberInput**

  - Set `NumberInput.Control` to include `NumberInput.IncrementTrigger` and
    `NumberInput.DecrementTrigger` as its default children, reducing LOC in
    common use cases.

- **QrCode**

  - Set `QrCode.Frame` to include `QrCode.Pattern` as its default children,
    reducing LOC in common use cases.

- **RatingGroup**

  - Set `RatingGroup.Control` to include an array of `RatingGroup.Item`
    components as its default children, reducing LOC in common use cases.

- **Slider**

  - Add `Slider.Marks` component to render marks on the slider track. This is a
    closed composition of `Slider.MarkerGroup` and `Slider.Marker` to reduce LOC
    for common use cases.
  - Add `Slider.Thumbs` component to render thumbs on the slider track. This is
    a closed composition of `Slider.Thumb` to reduce LOC for common use cases.

- **PinInput**

  - Add support for `attached` variant prop to render a pin input with attached
    inputs. This removes the need for the `Group` component to wrap the inputs.

- **Tooltip, Popover**

  - Set `Tooltip.Arrow` and `Popover.Arrow` to include `Tooltip.ArrowTip` and
    `Popover.ArrowTip` as its default children, reducing LOC in common use
    cases.

## [3.8.2](./#3.8.2) - 2025-03-04

### Fixed

- **AspectRatio:** Fix issue where `css` prop was not respected
- **System:** Fix issue where `mt` shorthand resolves to `marginBlockStart`
  instead of `marginTop`

## [3.8.1](./#3.8.1) - 2025-02-19

### Fixed

- Fix performance regression from `v3.5.x` by reverting memoization logic
- Add `useMemo` to provider components and styling hooks to avoid unnecessary
  recomputations

## [3.8.0](./#3.8.0) - 2025-02-09

### Added

- **[New] Hooks:**

  - `useElementRect`: Get the dimensions and position of an element
  - `useForceUpdate`: Force a component re-render
  - `useLiveRef`: Create a ref that stays up-to-date with its value
  - `usePrevious`: Access the previous value of a state or prop
  - `useSafeLayoutEffect`: A safer version of `useLayoutEffect`

- **[New] Focus Trap:** Add `FocusTrap` component for trapping focus within a
  container

### Fixed

- **Breadcrumb:** Fix issue where breadcrumb arrow doesn't flip in RTL mode
- **Group:** Fix issue where `Group` component doesn't skip invalid children

### Added

- **Color Mode:** Add `LightMode` and `DarkMode` components to force light and
  dark color mode in a subtree

## [3.7.0](./#3.7.0) - 2025-02-04

### Added

- **Avatar:** Add support for passing `name` to the `AvatarFallback` to render
  the initials. If no `name` or `children` is passed, it'll render either the
  initials or a fallback icon.

- **[New] Hooks:** Add `useConst` and `useUpdateEffect` hooks from v2.

- **[New] Wrap:** Bring back the `Wrap` component from v2.

## [3.6.0](./#3.6.0) - 2025-02-02

### Fixed

- **CLI:** Fix issue where CLI doesn't properly check for existing files when
  adding snippets.

### Added

- **[New] Close Button:** Add `CloseButton` component.
- **Stat:** Bring back `StatGroup` component from v2.
- **Avatar:** Bring back `AvatarGroup` component from v2.

### Changed

- **Styled System:**

  - Boost performance of style resolution by removing `JSON.stringify` in `memo`
    function and avoid memoizing non-primitive arguments.
  - Connect `assets` token to `backgroundImage` and `listStyleImage` css
    properties.

- **Menu, Tooltip:** Set `lazyMount` and `unmountOnExit` to `true` in the `Root`
  component to improve initial rendering performance.

- **AbsoluteCenter:** Fix issue where axis doesn't work in RTL mode.

- **Snippets / QRCode:** Remove snippet in favor of compound component pattern.

- **List:** Fix issue where list items don't wrap correctly.

## [3.5.1](./#3.5.1) - 2025-01-24

### Fixed

- **Button:** Fix issue where button is not disabled when loading props is
  passed

- **ColorPicker, HoverCard, Tooltip:** Fixed intermittent placement shifts
  caused by updates to the `data-placement` attribute

- **Snippets / Alert:** Deprecate the `Alert` snippet in favor of using the
  `Alert` component directly from `@chakra-ui/react`.

## [3.5.0](./#3.5.0) - 2025-01-24

### Fixed

- **Native Select**

  - Fix issue where `disabled` and `invalid` props were not being passed to the
    `NativeSelectField` component.
  - Persist error focus ring when `invalid` prop is set.
  - Fix issue where native select isn't readable in dark mode for Windows/Linux
    devices.

### Added

- **[New] Loader:** Add new `Loader` and `LoaderOverlay` components.

- **[New] Button Group:** Add new `ButtonGroup` component similar to v2 for
  grouping similar buttons.

- **Button:** Add `loading` and `loadingText` props to the `Button` component.

### Changed

- **Snippets / Menu:** Refactor checkbox item to fix rendering

- **Snippets / Button:** Removed the button snippet in favor of built-in
  component.

## [3.4.0](./#3.4.0) - 2025-01-17

### Added

- **[NEW] Presence:** Add new presence component to animate the entry and exit
  of an element while controlling the render behavior.

### Fixed

- **Separator**: Fix issue where `aria-orientation` was missing in the DOM and
  `orientation` was added instead.

- **Button, Icon** Fix issue where button and icon doesn't export props
  providers

- **System**: Fix performance issue where initial render time feels slower
  compared to v2 due to the global style computation in the provider component.
  [See Discussion](https://github.com/chakra-ui/chakra-ui/discussions/9488#discussioncomment-11868684)

- **FileUpload**
  - Resolved an issue where form-related components reset despite the reset
    event being cancelled.
  - Fixed a brief warning display when a new image file is added to the preview.
  - Enhanced click detection for the dropzone and added support for the
    `disableClick` prop.

## [3.3.3](./#3.3.3) - 2025-01-16

### Fixed

- **Icon**: Fix regression where icon sizes doesn't work anymore

## [3.3.2](./#3.3.2) - 2025-01-16

### Fixed

- **Icon**

  - Refactor icon recipe `size=inherit` to allow for composition with button
  - Fix issue where using `<Icon as={...} />` throws an error, forcing users to
    use the `asChild` approach

- **Menu, Select:** Use the same semantic token for select `_highlighted` state

- **Snippet, Tooltip:** Set `portalled` to `true` by default

- **Toast:** Fix issue where toast close trigger was not visible

- **Factory:** Fix issue where factory shows a warning React 19 due to accessing
  `child.ref`

## [3.3.1](./#3.3.1) - 2025-01-12

### Fixed

- **HoverCard, Tooltip**: Resolved an issue where the controlled open state
  could become inconsistent during the `opening` or `closing` phases.

- **System**: Fix issue where `useRecipe` and `useSlotRecipe` returns `never`
  when key does not match built-in recipe.

## [3.3.0](./#3.3.0) - 2025-01-09

### Added

- **[New] QRCode**: Add new component for converting text and links to QR codes.

```tsx
<QrCode.Root value="..." size="md">
  <QrCode.Frame>
    <QrCode.Pattern />
  </QrCode.Frame>
</QrCode.Root>
```

- **Clipboard**: Introduced `Clipboard.ValueText` to display clipboard content.

- **FileUpload**

  - Added `preventDropOnDocument` to block file drops on the document when the
    file upload component is active.

  - Added `setClipboardFiles` to the API for setting files from clipboard data.

- **Progress**: Added support for`onValueChange` and `defaultValue`.

- **Tabs, Menu**: Added `navigate` property for custom router navigation when
  selections render as links.

- **CLI**: Add support for `--tsx` flag in the `snippet add` command to allow
  explicitly specifying tsx/jsx file generation.

```bash
npx @chakra-ui/cli snippet add [...components] --tsx
```

- **[New] Panda**: Initial release of `@chakra-ui/panda-preset`. This allows you
  to use Chakra's design system in a Panda CSS project.

### Fixed

- **Collapsible**: Fixed a bug where the opening animation replayed when an open
  collapsible was re-rendered.

- **Dialog, Popover**: Fixed an issue causing dialogs or popovers to close if
  the focused element was removed from the DOM.

- **FileUpload**: Fixed a bug causing the hidden input to be out of sync with
  accepted files.

- **Menu, Popover**: Fixed inconsistent interaction detection outside the
  component when the trigger was inside a scrollable container.

- **Pagination**: Corrected an issue where the page range returned an incorrect
  `end` value when `pageSize` exceeded `count`.

- **Image**: Fix issue where `htmlWidth` and `htmlHeight` doesn't work in
  `Image` or `chakra.image` elements.

- **System**

  - Improve typesafety for layer styles to support common shorthands like `bg`,
    `bgColor`, `bgImage`.
  - Fix compound variant matching not working with `colorPalette` prop.

## [3.2.5](./#3.2.5) - 2025-01-04

### Fixed

- **useMediaQuery**: Fix issue where partial media queries like
  `aspect-ratio < 1` doesn't return the correct result.

  > **Good to know**: Partial media queries like `aspect-ratio < 1` resolves to
  > `aspect-ratio < 1 / 1` in the browser.

- **System**

  - Improve type-safety in `useRecipe` and `useSlotRecipe` hooks
  - Fix issue where composing `Input` component throws `asChild` React HTML prop
    warning.
  - Fix issue where `mergeConfigs` does not override functions

- **Snippets / Pagination**: Fix issue where pagination page text renders
  incorrectly when the `pageSize` is greater than the `count` value with
  `format=long`

- **Snippets / InputGroup**: Improve typings for `children` prop to prevent TS
  errors

- **FileUpload**: Resolved an issue where the `accept` attribute wasn’t applied
  to the hidden input.

- **NumberInput**: Fixed issue where the input event wasn’t triggered on the
  first click of the increment/decrement controls.

## [3.2.4](./#3.2.4) - 2024-12-30

### Fixed

- Fix issue where component hook props (like `UseCheckboxProps`,
  `UseCheckboxGroupProps`, etc.) are not exported.

- **System**: Fix issue where `chakra.x` factory component props throws TS error
  in React 19

## [3.2.3](./#3.2.3) - 2024-12-05

### Fixed

- **System**: Fix issue where responsive semantic tokens doesn't work as
  expected

## [3.2.2](./#3.2.2) - 2024-11-29

### Fixed

- **Slider**

  - Add `DraggingIndicator` component to show an element only while dragging
  - Fix issue where slider marks were not styled correctly in vertical
    orientation

- **Menu**: Update recipe to use `--available-height` css variable to keep the
  menu's height within the available space

- **System**: Fixed issue where exporting `withRootProvider` would result in
  type error

- **Snippets / Slider**

  - Move `MarkerGroup` into the `Control` component
  - Remove hardcoded margin values in favor of recipes and `data-has-mark-label`
    attribute

- **CLI**: Output the real version from `package.json`

## [3.2.1](./#3.2.1) - 2024-11-26

### Fixed

- **System**: Fix issue where exporting `withProvider` and `withContext` would
  result in type error

- **Timeline**: Fix issue where `TimelineTitle` was missing from the export

- **Tabs**: Fix issue where `useTabs` and `useTabsContext` were not exported

- **Snippets / ColorPicker**: Fix flex direction of `ColorPickerChannelInputs`
  and `ColorPickerChannelSliders`

- **CLI**

  - Fix issue where npmDependencies for snippets were not auto-installed
  - Support React Router 7 framework detection

## [3.2.0](./#3.2.0) - 2024-11-20

### Added

- **Input:** Add support for `use-mask-input` library to mask the input shape

- **CLI**: Add support for `--all` flag to add all snippets. By default, we only
  install a minimal/recommended set of snippets

  > **Recommended snippets:** provider, avatar, button, checkbox, radio,
  > input-group, slider, popover, dialog, drawer, tooltip, field

  If you want to add all snippets, you can use the `--all` flag

- **[Preview]** Add new `ColorPicker` component to allow users pick a color in
  hsl, rgb, hsb formats

- **[Preview]** Add new `ColorSwatch` component to preview a color

### Fixed

- **System**: Fix issue where `mergeConfigs` mutates the underlying configs
  passed to it

- **CLI:** Fix issue where typegen doesn't work when CLI installed globally or
  run using `npx`

## [3.1.2](./#3.1.2) - 2024-11-15

### Fixed

- **General:** Fix issue where value change types and components were not
  re-exported from Ark UI

- **Layer Style:** Fix issue where `fill.surface` layer style doesn't render the
  correct styles

- **Snippets / Pagination:** Fix issue where `PaginationPageText` did not render
  the correct page range

## [3.1.1](./#3.1.1) - 2024-11-09

### Fixed

- **Checkbox**: Fix issue where checkmark doesn't show on Safari

- **Alert**: Fix issue where indicator icon is not visible on Safari

- **ClientOnly**: Fix issue where returned the incorrect type leading to TS
  error like `ClientOnly cannot be used as a JSX component.`

- **Fieldset**: Fix issue where anatomy is not exported

- **Timeline**: Refactor variants such that it responds to `colorPalette`

- **useBreakpointValue**: Fix issue where hook throws error if `ssr` is `false`

## [3.1.0](./#3.1.0) - 2024-11-04

### Fixed

- **CLI**: Fix issue where adding a snippet with `--outdir` still creates
  snippets a `src/components/ui` directory.

- **System:** Fix issue where using `as` prop with logic based components
  doesn't work as expected.

### Added

- **DataList:** Add support for `bold` variant.

- **Toggle:** Add `Toggle` component for toggling between two states. It
  composes the `Button` component.

### Changed

- **Button:** Tweak the horizontal padding when size is `sm`.

- **Snippets**

  - Slider: Add `showValue` prop to render the text value of the slider.

  - Select

    - Add `HiddenSelect` to ensure it works in form submissions.
    - Fix type inference is lost when using `SelectRoot` component from snippet
    - Fix issue where form data is not populated when using native form element

  - ColorMode: Fix type error when using the latest `next-themes`.

  - Provider: Forward props to `ColorModeProvider` powered by `next-themes` for
    better customization.

## [3.0.2](./#3.0.2) - 2024-10-29

### Changed

- **Snippets / Toaster**: Improve toaster styling by adding
  `width={{ md: "sm" }}` to the toast root.

### Fixed

- **InputAddon**: Fix issue with input addon not stretched correctly.

- **CLI**

  - Fix issue with vite setup where `.mjs` and `mts` files were not considered.
  - Fix issue where style props types show as `any` when using `strictTokens`.

## [3.0.1](./#3.0.1) - 2024-10-25

### Changed

- Improve placeholder and selection styles

### Fixed

- Fix for custom keyframes not being picked up by autocomplete
- Fix issue where `scrollBehavior=outside` doesn't allow scrolling outside the
  dialog content

## [3.0.0](./#3.0.0) - 2024-10-22

### Changed

Visit the [Migration Guide](https://chakra-ui.com/docs/get-started/migration)
